Axiell Go installation guide - FreeBSD
IMPORTANT!
If you are installing Go in an environment alongside EMu 9.0 or later, DO NOT use these installation notes.
From EMu 9.0 onwards, Go is bundled with EMu and the installation notes on the EMu Support site must be used.
This guide describes how to install Axiell Go on a FreeBSD server, and how to troubleshoot an installation.
Axiell Go requires installation of two components:
- Axiell Go UI
- Axiell Go API
These are usually installed on the same server, although this is not a requirement. As described below, a number of other packages are also installed:
- An HTTP Server
- Java Runtime Environment
- Redis
Note:
- Access to the root account is required.
- Ability to edit text files from the command line is assumed.
- In the code examples below, code that must be modified to suit your environment is in highlighted with yellow
The Axiell Go User Interface (UI) is distributed as a static release bundle which can be served by almost any HTTP server.
Requirements
- HTTP Server
NGINX 1.10.0 or later recommended
-OR-
Apache 2.4 or later recommended
Instructions for both NGINX and Apache are provided.
- Axiell Go User Interface
Latest Axiell Go UI 1.x.x release bundle (details below).
- Login as root
- Run the command:
pkg install nginx
Progress messages will be displayed. Answer
y
whenever prompted, e.g.:Proceed with this action? [y/n]: y
- NGINX is configured using the file
nginx.conf
.Update the locate database and locate the NGINX configuration file by running:
/usr/libexec/locate.updatedb
locate nginx.conf
On FreeBSD systems this is typically found at:
/usr/local/etc/nginx/nginx.conf
- Edit the file:
/path to nginx/nginx.conf
- Locate the http context and within it the server entry:
http {
...
server {
# default virtual server configuration will appear here
.........
}
[We will insert an HTTP/HTTPS block of code here]
}
- One of the following blocks of code should be modified and inserted after the server entry (in the position indicated above).
The first block (7.1 below) creates an HTTP connection; the second (7.2) uses HTTPS / SSL to encrypt communications and is the recommended approach. The choice between the two is one for your local security policy.
Note: Use of HTTPS / SSL requires installation of a certificate.
IMPORTANT: Localization
The following lines (highlighted in the code below) must be changed to reflect your environment:
server_name
hostname;root /path to nginx/html/axiell-go-ui;
- server_name must be updated to reflect your hostname. To identify this, run:
hostname
- The root setting must reflect the location in which Axiell Go UI will be installed followed by /html/axiell-go-ui.
To determine this pathway, run:
locate nginx/html
If, for example, the server name is:
go.melbourne.axiell.com
and the pathway to the
nginx/html
directory is :/usr/share/etc/nginx/html
the following settings are required:
server_name go.melbourne.axiell.com;
root /usr/share/etc/nginx/html/axiell-go-ui;
7.1 HTTPAdd the following code to set up an HTTP connection, and save the file:
#
# Axiell Go API upstream config. This specifies the host and port of the Axiell
# Go API. Port 8443 should be used when Go API has HTTPS/SSL enabled.
#
upstream axiell_go_api {
server 127.0.0.1:8000;
keepalive 64;
}
#
# Virtual Server for Axiell Go UI
server {
# HTTP
listen 81 default_server;
listen [::]:81 default_server;
# HTTPS
# listen 443 ssl http2 default_server;
# listen [::]:443 ssl http2 default_server;
#
# ssl_certificate "/etc/pki/nginx/server.crt";
# ssl_certificate_key "/etc/pki/nginx/private/server.key";
# ssl_session_cache shared:SSL:1m;
# ssl_session_timeout 10m;
# ssl_ciphers HIGH:!aNULL:!MD5;
# ssl_prefer_server_ciphers on;
server_name hostname;
root /path to nginx/html/axiell-go-ui;
gzip_static on;
client_max_body_size 100M;
# HTML5 History fallback
location / {
try_files $uri $uri/ /index.html;
}
#
# Forwards all requests to /api on to http://axiell_go_api/
#
location /api {
rewrite /api/(.*) /$1 break;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Prefix '/api';
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-Port $http_port;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-NginX-Proxy true;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_max_temp_file_size 0;
proxy_pass http://axiell_go_api/;
proxy_redirect off;
proxy_read_timeout 240s;
}
}
7.2 HTTPS / SSLAdd the following code to set up an HTTPS / SSL connection, and save the file:
#
# Axiell Go API upstream config. This specifies the host and port of the Axiell
# Go API. Port 8443 should be used when Go API has HTTPS/SSL enabled.
#
upstream axiell_go_api {
server 127.0.0.1:8443;
keepalive 64;
}
#
# Virtual Server for Axiell Go UI
server {
# HTTP
# listen 81 default_server;
# listen [::]:81 default_server;
# HTTPS
listen 443 ssl http2 default_server;
listen [::]:443 ssl http2 default_server;
#
ssl_certificate "/etc/pki/nginx/server.crt";
ssl_certificate_key "/etc/pki/nginx/private/server.key";
ssl_session_cache shared:SSL:1m;
ssl_session_timeout 10m;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
server_name hostname;
root /path to nginx/html/axiell-go-ui;
gzip_static on;
client_max_body_size 100M;
# HTML5 History fallback
location / {
try_files $uri $uri/ /index.html;
}
# Forwards all requests to /api on to http://axiell_go_api/
location /api {
rewrite /api/(.*) /$1 break;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Prefix '/api';
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-Port $http_port;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-NginX-Proxy true;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_max_temp_file_size 0;
proxy_pass http://axiell_go_api/;
proxy_redirect off;
proxy_read_timeout 240s;
}
}
Security certificates
Implementation of a secure connection entails use of a public / private key combination. If these have not been created for your server, it will be necessary to obtain them from a certificate authority.
Three files with the following extensions will be provided:
- .crt (a security certificate file)
- .ca-bundle (root and intermediate certificates)
- .key (private key, this must never be shared as it would compromise security)
Find out from the supplier of the keys what passwords are associated with them. At a minimum the private key (.key) will have a password. A password for the public key (.crt) may also have been set. Note these for inclusion in the Java configuration later.
- Download the three files to the /tmp directory on the server.
NGINX requires the .crt and .ca-bundle files to be combined. This can be done as follows:
cd /tmp
cat filename.crt My_CA_Bundle.ca-bundle > server.crt
where filename is the name of your .crt file; and My_CA_Bundle is the name of your combined files.
Move the files to the appropriate directories as follows:
mv server.crt /etc/pki/nginx/server.crt
mkdir -p /etc/pki/nginx/private
mv filename.key /etc/pki/nginx/private/server.key
where filename is the name of your .key file.
- server_name must be updated to reflect your hostname. To identify this, run:
- Download the latest Axiell Go UI release bundle.
The latest release appears in the Go User Interface section and is named axiell-go-release-n.n.n-install.zip where n.n.n is the release number.
Place this in the /tmp directory on the server. This must be extracted into the directory defined by the root setting above.
Enter:mkdir –p /path to nginx/html/axiell-go-ui
cd /path to nginx/html/axiell-go-ui
mv /tmp/axiell-go-release-n.n.n-install.zip .
unzip axiell-go-release-n.n.n-install.zip
- Enable NGINX at system boot.
Edit
/etc/rc.conf
Add the following line:
nginx_enable="YES"
If the following line is present:
firewall_enable="YES"
ensure the setting for
firewall_myservices
includes80/tcp
(if using HTTP) or443/tcp
(if using HTTPS/SSL). For examplefirewall_myservices="22/tcp 80/tcp 443/tcp"
allows connections via ssh, HTTP and HTTPS.
- Start NGINX by running:
service nginx start
-
Check NGINX is running by checking its status:
service nginx status
Troubleshooting
If starting the service generates error messages complaining that:
nginx: [emerg] socket() [::]:80 failed (43: Protocol not supported)
it is likely that your system does not support ipv6. To resolve this edit the nginx.conf file and comment out the line commencing with:
listen [::]:
and rerun
service nginx start
If NGINX fails to start and produces an error message containing text along the lines of:
nginx: [emerg] bind() to 0.0.0.0:80 failed (48: Address already in use)
the port configured for use by nginx, 80 in the example above, is already being used, say by apache. In this case, the user can choose to disable the existing service or change the port number nginx is using.
Unless it is known that the existing service is not required, the latter option is better.
To change the nginx port, edit the nginx.conf
file and alter to a new port, say 8080. Save the file and rerun:
service nginx start
- Login as root
- Run the command:
pkg install apache24
Progress messages will be displayed. Answer
y
whenever prompted, e.g.:Proceed with this action? [y/n]: y
- Create the file:
/usr/local/etc/apache24/Includes/axiell-go.conf
-
Add the following configuration for HTTP access:
listen 80
<VirtualHost *:80>
DocumentRoot "/usr/local/www/apache24/axiell-go-ui"
<Directory /usr/local/www/apache24/axiell-go-ui>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Require all granted
</Directory>
<Location "/api">
ProxyPreserveHost On
RequestHeader set X-Forwarded-Port "8002"
RequestHeader set X-Forwarded-Proto "http"
RequestHeader set X-Forwarded-Prefix "/api"
RequestHeader set Connection "upgrade"
ProxyPass "http://hostname:8000" timeout=600
ProxyPassReverse "http://hostname:8000"
</Location>
</VirtualHost>
-
Add the following configuration for HTTPS access:
listen 443
<VirtualHost *:443>
DocumentRoot "/usr/local/www/apache24/axiell-go-ui"
SSLEngine on
SSLCertificateFile /usr/local/etc/apache24/Includes/axiell-go.crt
SSLCertificateKeyFile /usr/local/etc/apache24/Includes/axiell-go.key
SSLCertificateChainFile /usr/local/etc/apache24/Includes/axiell-go.ca-bundle
ServerName hostname
<Directory /usr/local/www/apache24/axiell-go-ui>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Require all granted
</Directory>
<Location "/api">
ProxyPreserveHost On
RequestHeader set X-Forwarded-Port "8002"
RequestHeader set X-Forwarded-Proto "http"
RequestHeader set X-Forwarded-Prefix "/api"
RequestHeader set Connection "upgrade"
ProxyPass "http://hostname:8443" timeout=600
ProxyPassReverse "http://hostname:8443"
</Location>
</VirtualHost>
Security certificates
Implementation of a secure connection entails use of a public / private key combination. If these have not been created for your server, it will be necessary to obtain them from a certificate authority.
Three files with the following extensions will be provided:
- .crt (a security certificate file)
- .ca-bundle (root and intermediate certificates)
- .key (private key, this must never be shared as it would compromise security)
Find out from the supplier of the keys what passwords are associated with them.
- Download the three files to the /tmp directory on the server. If any of the files have a password set, remove the password (see openssl for details on how to remove passwords).
-
Move the files to the appropriate directories as follows:
mv server.crt /usr/local/etc/apache24/Includes/axiell-go.crt
mv server.key /usr/local/etc/apache24/Includes/axiell-go.key
mv server.ca-bundle /usr/local/etc/apache24/Includes/axiell-go.ca-bundle
- Download the latest Axiell Go UI release bundle.
The latest release appears in the Go User Interface section and is named axiell-go-release-n.n.n-install.zip where n.n.n is the release number.
Place this in the /tmp directory on the server. This must be extracted into the directory defined by the root setting above.
Enter:mkdir –p /usr/local/www/apache24/axiell-go-ui
cd /usr/local/www/apache24/axiell-go-ui
mv /tmp/axiell-go-release-n.n.n-install.zip .
unzip axiell-go-release-n.n.n-install.zip
- Enable Apache at system boot.
Edit
/etc/rc.conf
Add the following line:
apache24_enable="YES"
If the following line is present:
firewall_enable="YES"
ensure the setting for
firewall_myservices
includes80/tcp
(if using HTTP) or443/tcp
(if using HTTPS/SSL). For examplefirewall_myservices="22/tcp 80/tcp 443/tcp"
allows connections via ssh, HTTP and HTTPS.
- Start Apache by running:
service apache24 start
-
Check Apache is running by checking its status:
service apache24 status
- Java Runtime Environment version 8 (preferred) or 11
- Redis 3.0.0 or later
- Latest Go API 1.x.x release bundle (details below)
- Login as root
- Install OpenJDK Java Runtime Environment.
It is recommended that version 8 of the Java Development Kit (JDK) or Java Run Time Kit (JRE) is installed.
Run
pkg search openjdk
Identify the Java release 8 package for either JDK or JRE, e.g.:
openjdk8-8.312.07.1
Java Development Kit 8
or
openjdk8-jre-8.312.07.1
Java Runtime Environment 8
Install it using:
pkg install
java-package-release
- Verify that Java was successfully installed by running:
java -version
It is highly recommended that Redis is installed on the same server running the Axiell Go API.
- Login as root
- Install Redis by running:
pkg install redis
If any custom Redis configuration is required, edit the Redis configuration file and modify as necessary:
/usr/local/etc/redis.conf
Note: Successful installation of Axiell Go does not require specific changes to this file.
Enable the Redis service at system boot:
-
Edit
/etc/rc.conf
-
Add the following line:
redis_enable="YES"
Start Redis:
-
Login as
root
-
Start Redis by running:
service redis start
Check Redis status:
-
Login as
root
-
Check Redis Status by running
service redis status
- Login as root
-
Create group
go
by running:pw groupadd go
-
Add user
go
, noting that:- the specification of the home directory
/home/go
may need to be changed to reflect your local file system; and - the shell
/bin/sh
may be changed to suit your preference, e.g./usr/local/bin/bash
Run:
pw useradd -n go -c "Axiell Go Administrator" -d /home/go -m -s /usr/local/bin/bash -g go
- the specification of the home directory
-
Log in as user
go
- Download the latest
go-api-server-n.n.n.zip
Go API release bundle, saving in the home directory. n.n.n is the release number. -
Extract the release. Run:
unzip go-api-server-n.n.n.zip
Create a symbolic link to the new release. Run:
ln -s go-api-server-n.n.n go-api-server
-
Login as user
root
-
Edit
/usr/local/etc/rc.d/go
-
Add the following lines, if necessary replacing the string
/home/go
to reflectgo
’s home directory#!/bin/sh
#
# PROVIDE: go
# REQUIRE: LOGIN
# KEYWORD: shutdown
. /etc/rc.subr
name="go"
rcvar="go_enable"
load_rc_config $name
: ${go_enable:="no"}
:
${go_home:="/home/go/go-api-server"}
: ${go_user:="go"}
: ${go_group:="go"}
: ${go_cmd:="${go_home}/bin/go-api-server"}
: ${go_args:=""}
required_dirs="${go_home}"
pidfile="/var/run/${name}.pid"
command="/usr/sbin/daemon"
command_args="-c -f -P ${pidfile} ${go_cmd} \
-Dgo.home=${go_home} \
-Dlogback.configurationFile=${go_home}/conf/logback.xml \
${go_args}"
start_precmd="touch ${pidfile} && \
chown ${go_user}:${go_group} ${pidfile}"
run_rc_command "$1"
-
Enter
chmod 755 /usr/local/etc/rc.d/go
-
Edit
/etc/rc.conf
and append the following lines, noting that the path/usr/local/openjdk8/jre/lib/security
may need to be changed to reflect the version of Java installed.The file below is configure for use of HTTPS/SSL. If using HTTP, uncomment the first
go_args
line and comment out the second.go_enable="YES"
#
# Axiell Go Arguments
#
# GO_SERVER_INTERFACE : IP Address of Axiell Go serv host
# GO_SERVER_PORT : 8000 or 8443 is keystore is configured below
# GO_DATA_URI : IP & Port of IMu server on EMu host
# : Format is emu://hostname:port
#
# GO_STORAGE_URI : Redis URI
# : Format is redis://[password@]hostname:port
# Keystore, use when HTTPS/SSL is required
# GO_KEYSTORE_PATH : /path/to/keystore.jks or cacerts file of jdk
#
# GO_KEYSTORE_PASSWORD : public_key_password
# GO_KEYSTORE_KEY_PASSWORD: private_key_password
#
# HTTP
# go_args="-DGO_SERVER_INTERFACE=127.0.0.1 -DGO_SERVER_PORT=8000 -DGO_DATA_URI=emu://127.0.0.1:40193 -DGO_KEYSTORE_PATH=/usr/local/openjdk8/jre/lib/security"
#HTTPS/SSL
go_args="-DGO_SERVER_INTERFACE=127.0.0.1 -DGO_SERVER_PORT=8443 -DGO_DATA_URI=emu://127.0.0.1:40193 -DGO_KEYSTORE_PATH=/usr/local/openjdk8/jre/lib/security GO_KEYSTORE_PASSWORD=public_key_password GO_KEYSTORE_KEY_PASSWORD=private_key_password"
-
Start the service. Run:
service go start
-
Check the service is running by entering:
service go status
Go Requirements
- EMu Version 6.0-1905101 or later
- IMu server enabled
Go Setup Script
The are some additional steps required to configure an EMu backend for Axiell Go:
- Login as emu
- Type gosetup
The gosetup script performs the following:
- Installs
CPAMN
. - Installs required Perl modules via
CPANM
. - Inserts required Registry entries.
- Installs
IMu Server
Axiell Go connects to EMu via IMu server and requires that the imu
load is enabled and running:
- See the EMu 6 installation notes for details about enabling and configuring the IMu server.
- Ensure that any firewalls are configured to allow connections via the following IMu ports from the server running Axiell Go API. The ports can be determined by looking in the IMu server configuration file found at ~emu/etc/imuserver.conf on the EMu server:
- main-port (e.g. 40193)
- reconnect-port range suitable for expected number of connections (e.g.: opening ports 45000-45010 would allow for up to 10 authenticated IMu sessions).
- Be sure that the IMu server trace-level value is set to 1 in ~emu/etc/imuserver.conf.
Setting the trace level this low will prevent excessive logging information being generated in production environments.
Once the above steps are complete, restart IMu by restarting the EMu server load:
- Type emuload restart imu